<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
  "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
  <title>Compiling.html</title>
  <meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
  <style type="text/css">
  <!--
    body {
      font-family: Verdana,Helvetica,Arial,sans-serif;
      font-size: small;
    }
    code,pre {
      font-family: "Courier New",Courier,monospace;
      font-size: 1em;
    }
    h3 {
      padding: 2px;
      border-left: 4px solid #FFCC00;
      border-bottom: 1px solid #FFCC00;
    }
    h4 {
      padding: 2px;
      border-left: 8px solid #FF9933;
      border-bottom: 1px solid #FF9933;
    }
    h5 {
      font-size: small;
    }
    pre {
      margin-left: 25px;
      margin-right: 25px;
      padding: 5px;
      background-color: #EEEEEE;
      border-left: 10px solid #CCCCCC;
    }
    p.note {
      padding: 5px;
      background-color: #DDDDFF;
      border: 1px solid #6666FF;
    }
    acronym {
      cursor: help;
      border-bottom: 1px dotted black;
    }
  -->
  </style>
</head>
<body>
<h2>Compiling WinMerge</h2>

<p>Compiling sources is usually the first thing you want to do. Source packages
for different versions are available from SourceForge.net downloads or from
Subversion repository. See <a href="readme-Subversion.html">readme-Subversion.html
</a> for more information about Subversion repository and using it.</p>

<h3>Table of Contents</h3>
<ol>
  <li><a href="#Environment">Environment</a></li>
  <li><a href="#ProjectFiles">Project Files</a></li>
  <li><a href="#Compiling_expat">Compiling expat</a></li>
  <li><a href="#Compiling_scew">Compiling SCEW</a></li>
  <li><a href="#Compiling_pcre">Compiling PCRE</a></li>
  <li><a href="#Compiling_core">Compiling WinMerge executables</a></li>
  <li><a href="#ShellExt64">Shell Extension (64-bit)</a></li>
  <li><a href="#VS2005">Visual Studio 2005 & 2008 Manifest File</a></li>
  <li><a href="#64bit">Building 64-bit version</a></li>
</ol>


<h3><a name="Environment">Environment</a></h3>
<h4>Supported Compilers</h4>

<p>Compiling WinMerge requires commercial edition of the Visual Studio. Free
Express Editions cannot be used since they don't include MFC. WinMerge uses
MFC for the GUI.</p>

<ul>
  <li>Visual Studio 2003.Net + Service Pack 1</li>
  <li>Visual Studio 2005 (occasional checks for compiling) (Service Pack 1
    recommended)</li>
  <li>Visual Studio 2008 (Service Pack 1 recommended)  [<i>used for releases</i>]</li>
  <li>Visual Studio 2010</li>
</ul>

<h4>Libraries</h4>
<p>WinMerge executable depends on Expat XML parser, SCEW and PCRE libraries.
All are in the source tree (in <code>/Externals</code> -folder), and need to be
compiled before compiling WinMerge executable.</p>

<p class="note"><b>Visual Studio 2008 and later:</b> You'll need to convert
library workspace and project files to new format before compiling.</p>

<p> To convert workspace/project files, just open them into Visual Studio and
let the Visual Studio to convert. Files are:
<ul>
  <li><code>WinMerge.sln</code></li>
  <li><code>Externals\expat\expat.sln</code></li>
  <li><code>Externals\scew\win32\scew.vcproj</code></li>
  <li><code>Externals\pcre\pcre.sln</code></li>
</ul>
There is a Python script <code>/Tools/Scripts/UpgradeProjects.py</code> which
updates most solution/project files.</p>

<h4>Additional requirements (out of source tree)</h4>
<ul>
  <li>HTML Help Workshop (either stand-alone or from Platform SDK)<br>
    Download it from :<a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp">
    HTMLHelp download</a>.</li>
  <li>Platform SDK or Windows SDK:
    <ul>
      <li>Platform SDK Windows 2003 SP1 -
       <a href="http://www.microsoft.com/downloads/details.aspx?familyid=0BAF2B35-C656-4969-ACE8-E4C0C0716ADB">
       Download and install</a></li>
      <li>Windows SDK -
       <a href="http://msdn.microsoft.com/en-us/windowsserver/bb980924.aspx">
       Download and install</a></li>
    </ul>
    Visual Studio 2003.Net and later come with Platform SDK but you may still want more recent version...</li>
  <li>Installer needs own tools, documented in <a href="readme-InnoSetup.html">readme-InnoSetup.html</a></li>
  <li>Manual needs Docbook tools, documented in <a href="readme-manual.html">readme-manual.html</a></li>
</ul>

<h5>Platform SDK components</h5>
<p>Needed Platform SDK components:</p>
<ul>
  <li>Microsoft Windows Core SDK - obviously..</li>
  <li>Microsoft Data Access Services (MDAC) SDK - for some ODBC etc headers needed by other PSDK headers..</li>
  <li>Microsoft Web Workshop (IE) SDK - for IE/Shell headers</li>
</ul>
<p class="note">If you installed PSDK separately, don't forget to add the PSDK paths to Visual
Studio's <em>Include</em> and <em>Library</em> directories. The easiest way is to use the
"<em>Visual Studio Registration\Register PSDK directories with Visual Studio</em>" item from
the "<em>Platform SDK</em>" start menu folder.</p>

<h3><a name="ProjectFiles">Project files</a></h3>
<p>Project file for WinMerge executable (in <code>/Src</code>) and other projects like
ShellExtension (in <code>/ShellExtension</code>) have their own project files. There is no one
single project/workspace file to compile all projects.<p>

<p>The Visual Studio project and solution files for VS2005 come with the
WinMerge sources. Newer versions of Visual Studio can open that file too, they
just ask if one wants to convert to the new version. The reason we don't ship
project files for all Visual Studio versions is we have no resources
to keep all versions up to date. People can't test all versions themselves, and easily forget
to update at least one file. So we easily end up in a situation where there is no properly
working project file at all...</p>

<p>After opening the project file you need to add the HTML Help Workshop path as additional include-
and library-path.</p>

<p class="note"><b>NOTE:</b> There might be problems compiling/debugging with Visual Studio 2003 when using
HTML Help WorkShop from the Platform SDK in Visual Studio directory. Download and
install HTML Workshop as stand-alone and include headers and libraries from standalone
directory. The probable cause is that including files from Platform SDK directories breaks
things.</p>

<h3><a name="Compiling_expat">Compiling expat</a></h3>
<p>expat is in <code>/Externals/expat</code> folder in source tree. To compile expat:</p>
<ul>
  <li>Open Visual Studio solution <code>/Externals/expat/expat.sln</code>. If you are
    using Visual Studio 2008 or later you need to convert the file to the new format when
    Visual Studio opens the file.</li>
  <li>Select from Visual Studio menu Build / Batch Build</li>
  <li>Select either debug or release targets.</li>
  <li>Select Rebuild All</li>
 </ul>

<p>After build finishes, selected (debug or release) lib and dll files are in
<code>/Build/expat</code>. WinMerge executable's project file picks them from there.</p>

<h3><a name="Compiling_scew">Compiling scew</a></h3>
<p>scew is in <code>/Externals/scew</code> folder in source tree. To compile scew:</p>
<ul>
  <li>Open Visual Studio project file <code>/Externals/scew/win32/scew.vcproj</code> If you are
    using Visual Studio 2008 or later you need to convert the file to the new format when
    Visual Studio opens the file.</li>
  <li>Select from Visual Studio menu Build / Batch Build</li>
  <li>Make sure all targets are selected</li>
  <li>Select Rebuild All</li>
</ul>

<h3><a name="Compiling_pcre">Compiling PCRE</a></h3>
<p>PCRE is in <code>/Externals/pcre</code> folder in source tree. PCRE uses
CMake (<a href="http://www.cmake.org/">http://www.cmake.org/</a>) to create
project- and solution-files. There are ready-made files in our source tree.</p>

<p>To compile PCRE:</p>
<ul>
  <li>Open Visual Studio solution file <code>/Externals/pcre/Win32/pcre.sln</code> If you are
    using Visual Studio 2008 or later you need to convert the file to the new format when
    Visual Studio opens the file.</li>
  <li>Select the <code>MinSizeRel</code>-target.</li>
  <li>Build the <code>pcre</code>-project
</ul>

<p>After build finishes, lib and dll files are in <code>/Build/pcre</code>. WinMerge
executable's project file picks them from there.</p>

<p>If you want to re-build PCRE from the scratch, including project files, see
file <code>Externals/pcre/NON-UNIX-USE</code>. There are instructions for
running CMake and using it to configure PCRE.</p>

<p>When configuring PCRE, remember to set these two options:
<ul>
  <li>Build shared libraries (to create DLL files, not static libraries)</li>
  <li>Enable using <code>ANYCRLF</code> or <code>ANY</code> as linefeed style.
    Current build uses <code>ANY</code>.</li>
  <li>Enable using UTF-8</li>
</ul></p>

<p>After CMake finishes, there are project files in the folder you selected as
a build folder. However all paths in the files are absolute, not relative. If
you want to make these files useful for other users you'll need to convert all
paths to relative paths. In addition you need to remove custom build rules for
building <code>CMakeLists.txt</code>. That rule tries to run CMake to re-generate
some files.

<h3><a name="Compiling_core">Compiling WinMerge executable targets</a></h3>
<p>There are several targets available for compiling different projects. Targets used
for compiling releases are:<br>
<ul>
  <li><code>WinMergeU.exe</code> : UnicodeRelease</li>
  <li><code>ShellExtensionU.dll</code> : Unicode Release MinDependency</li>
  <li>Plugin dlls : Unicode Release MinDependency</li>
</ul>

<h3><a name="ShellExt64">Shell Extension (64-bit)</a></h3>
<p>Visual Studio 2005 and later come with 64-bit compiler. To compile 64-bit
ShellExtension, open the <code>ShellExtension.vcproj</code> -project file
and select X64 Debug or X64 Release -target. Then compile as usual.</p>

<p>If you are compiling in 32-bit Windows you get error about registering
but that is expected to happen.</p>

<p>64-bit ShellExtension is registered to 64-bit Windows just like counterparts in 32-bit world:<br>
<code>regsvr ShellExtensionX64.dll</code></p>

<h3><a name="VS2005">Visual Studio 2005 & 2008 Manifest File</a></h3>
<p>When the VC6 project file (.dsp) is converted to a Visual Studio 2005 or
2008 project, the visual styles do not get enabled. The problem is Visual Studio
2005 and 2008 automatically generates and embeds a manifest file for the
executable, but that generated manifest does not include all needed properties
to enable visual styles. The solution is to add WinMerge's manifest file as
additional manifest.</p>

<p>From project properties, set<br>
  <code>Manifest Tool / Input and Output / Additional Manifest Files</code> -property value to:<br>
  <code>$(InputDir)\res\$(TargetFileName).manifest</code>
</p>

<p>There is a Python script <code>Tools/Scripts/fix_manifest.py</code> which
does the conversion. Note that the script re-formats the project file XML
structure when saving so do not generate patches without first opening and
saving the project file with Visual Studio.</p>

<p>See also <a href="http://forums.microsoft.com/MSDN/ShowPost.aspx?PostID=143306&SiteID=1">
Manifests in VS2005-- What are they?</a> -thread in Microsoft forum.
</p>

<h3><a name="64bit">Building 64-bit version</a></h3>
<p><b>64-bit versions are not supported.</b> We provide project
files for building 64-bit version of WinMerge so people can start testing and
experimenting it. But it is still a long way to make actual releases of 64-bit
versions.
</p>

<p>Project files for 64-bit versions (at the moment) work only with VS2008.
There might be later project files compatible with VS2005, but don't count on
it. The project files are named as <code><i>[projectname]</i>X64.vcproj</code>.
</p>

<h4>Bugs and patches</h4>
<p>Submit bugs about 64-bit builds to our bug tracker as usual. But also expect
they are given low priority. Likewise patches can be submitted to our patch
tracker.</p>

</body>
</html>